<!DOCTYPE html>
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.21.2: https://docutils.sourceforge.io/" />
<title>libtorrent</title>
<meta name="description" content="A feature complete BitTorrent protocol implementation as a C++ library">
<meta name=viewport content="width=device-width, initial-scale=1">
<meta property="og:image" content="img/logo-color.png" />
<meta property="og:site_name" content="libtorrent" />
<link rel="stylesheet" href="style.css" type="text/css" />
</head>
<body>
<div class="document" id="libtorrent-python-binding">
    <div id="container">
    <a href="index.html">
    <img src="img/logo-color-text.png" alt="libtorrent logo"/>
    </a>
    <div>
<h1 class="title">libtorrent python binding</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Version:</th>
<td>2.0.11</td></tr>
</tbody>
</table>
<div class="contents topic" id="table-of-contents">
<p class="topic-title">Table of contents</p>
<ul class="simple">
<li><a class="reference internal" href="#building" id="toc-entry-1">building</a></li>
<li><a class="reference internal" href="#prerequisites" id="toc-entry-2">prerequisites</a><ul>
<li><a class="reference internal" href="#environment-variables" id="toc-entry-3">environment variables</a></li>
</ul>
</li>
<li><a class="reference internal" href="#building-with-setup-py" id="toc-entry-4">building with setup.py</a><ul>
<li><a class="reference internal" href="#build-for-a-different-python-version" id="toc-entry-5">build for a different python version</a></li>
<li><a class="reference internal" href="#customizing-the-build" id="toc-entry-6">customizing the build</a></li>
</ul>
</li>
<li><a class="reference internal" href="#building-with-b2" id="toc-entry-7">building with b2</a><ul>
<li><a class="reference internal" href="#invoking-b2" id="toc-entry-8">invoking b2</a></li>
<li><a class="reference internal" href="#static-linking" id="toc-entry-9">static linking</a></li>
<li><a class="reference internal" href="#helper-targets" id="toc-entry-10">helper targets</a></li>
</ul>
</li>
<li><a class="reference internal" href="#using-libtorrent-in-python" id="toc-entry-11">using libtorrent in python</a></li>
<li><a class="reference internal" href="#set-alert-notify" id="toc-entry-12">set_alert_notify</a></li>
<li><a class="reference internal" href="#example" id="toc-entry-13">Example</a></li>
</ul>
</div>
<div class="section" id="building">
<h1>building</h1>
<p>libtorrent can be built as a python module.</p>
<p>The best way to build the python bindings is using <tt class="docutils literal">setup.py</tt>. This invokes
<tt class="docutils literal">b2</tt> under the hood, so you must have all of libtorrent's build dependencies
installed.</p>
<p>If you just want to build the shared library python extension without python
packaging semantics, you can also invoke <tt class="docutils literal">b2</tt> directly.</p>
</div>
<div class="section" id="prerequisites">
<h1>prerequisites</h1>
<p>Whether building with <tt class="docutils literal">setup.py</tt> or directly invoking <tt class="docutils literal">b2</tt>, you must
install the build prerequisites on your system:</p>
<ol class="arabic simple">
<li>All <a class="reference external" href="building.html">the build prerequisites for the main libtorrent library</a>, including
boost libraries and <tt class="docutils literal">b2</tt>, and your building toolchain (<tt class="docutils literal">gcc</tt>, visual
studio, etc).</li>
<li>Boost.Python, if not otherwise included in your boost installation</li>
<li>Python 3.7+. Older versions may work, but are not tested.</li>
</ol>
<div class="section" id="environment-variables">
<h2>environment variables</h2>
<p><tt class="docutils literal">b2</tt> is very sensitive to environment variables. At least the following are
required:</p>
<ol class="arabic simple">
<li><tt class="docutils literal">BOOST_ROOT</tt></li>
<li><tt class="docutils literal">BOOST_BUILD_PATH</tt></li>
</ol>
<p><tt class="docutils literal">b2</tt> is also known to reference dozens of other environment variables when
detecting toolsets. Keep this in mind if you are building in an isolation
environment like <tt class="docutils literal">tox</tt>.</p>
</div>
</div>
<div class="section" id="building-with-setup-py">
<h1>building with setup.py</h1>
<p>By default, <tt class="docutils literal">setup.py</tt> will invoke <tt class="docutils literal">b2</tt> to build libtorrent:</p>
<pre class="literal-block">
python setup.py build
</pre>
<p><tt class="docutils literal">setup.py</tt> is a normal <tt class="docutils literal">distutils</tt>-based setup script.</p>
<p>To install into your python environment:</p>
<pre class="literal-block">
python setup.py install
</pre>
<p>To build a binary wheel package:</p>
<pre class="literal-block">
python -m pip install wheel
python setup.py bdist_wheel
</pre>
<div class="section" id="build-for-a-different-python-version">
<h2>build for a different python version</h2>
<p><tt class="docutils literal">setup.py</tt> will target the running interpreter. To build for different python
versions, you must change how you invoke <tt class="docutils literal">setup.py</tt>:</p>
<pre class="literal-block">
# build for python3.7
python3.7 setup.py build
# build for python3.7
python3.7 setup.py build
</pre>
</div>
<div class="section" id="customizing-the-build">
<h2>customizing the build</h2>
<p>You can customize the build by passing options to the <tt class="docutils literal">build_ext</tt> step of
<tt class="docutils literal">setup.py</tt> by passing arguments directly to <tt class="docutils literal">b2</tt> via <tt class="docutils literal"><span class="pre">--b2-args=</span></tt>:</p>
<pre class="literal-block">
python setup.py build_ext --b2-args=&quot;toolset=msvc-14.2 linkflags=-L../../src/.libs&quot;
</pre>
<p>For a full list of <tt class="docutils literal">b2</tt> build options, see <a class="reference external" href="building.html#build-features">libtorrent build features</a>.</p>
<p>Here, it's important to note that <tt class="docutils literal">build_ext</tt> has no &quot;memory&quot; of the build
config and arguments you passed to it before. This is <em>different</em> from the way
<tt class="docutils literal">distutils</tt> normally works. Consider:</p>
<pre class="literal-block">
python setup.py build_ext --b2-args=&quot;optimization=space&quot;
# the following will build with DEFAULT optimization
python setup.py install
</pre>
<p>In order to customize the build <em>and</em> run other steps like installation, you
should run the steps inline with <tt class="docutils literal">build_ext</tt>:</p>
<pre class="literal-block">
python setup.py build_ext --b2-args=&quot;optimization=space&quot; install
</pre>
</div>
</div>
<div class="section" id="building-with-b2">
<h1>building with b2</h1>
<p>You will need to update your <tt class="docutils literal"><span class="pre">user-config.jam</span></tt> so <tt class="docutils literal">b2</tt> can find your python
installation.</p>
<p><tt class="docutils literal">b2</tt> has some auto-detection capabilities. You may be able to do just this:</p>
<pre class="literal-block">
using python : 3.7 ;
</pre>
<p>However you may need to specify full paths. On windows, it make look like
this:</p>
<pre class="literal-block">
using python : 3.7 : C:/Users/&lt;UserName&gt;/AppData/Local/Programs/Python/Python36 : C:/Users/&lt;UserName&gt;/AppData/Local/Programs/Python/Python36/include : C:/Users/&lt;UserName&gt;/AppData/Local/Programs/Python/Python36/libs ;
</pre>
<p>Or on Linux, like this:</p>
<pre class="literal-block">
using python : 3.7 : /usr/bin/python3.7 : /usr/include/python3.7 : /usr/lib/python3.7 ;
</pre>
<p>Note that <tt class="docutils literal">b2</tt>'s python path detection is known to only work for global
python installations. It is known to be broken for virtualenvs or <tt class="docutils literal">pyenv</tt>. If
you are using <tt class="docutils literal">pyenv</tt> to manage your python versions, you must specify full
include and library paths yourself.</p>
<div class="section" id="invoking-b2">
<h2>invoking b2</h2>
<p>Build the bindings like so:</p>
<pre class="literal-block">
cd bindings/python
b2 release python=3.7 address-model=64
</pre>
<p>Note that <tt class="docutils literal"><span class="pre">address-model</span></tt> should match the python installation you are
building for.</p>
<p>For other build features, see <a class="reference external" href="building.html#build-features">libtorrent build options</a>.</p>
</div>
<div class="section" id="static-linking">
<h2>static linking</h2>
<p>A python module is a shared library. Specifying <tt class="docutils literal">link=static</tt> when building
the binding won't work, as it would try to produce a static library.</p>
<p>Instead, control whether the libtorrent main library or boost is linked
statically with <tt class="docutils literal"><span class="pre">libtorrent-link=static</span></tt> and <tt class="docutils literal"><span class="pre">boost-link=static</span></tt>
respectively.</p>
<p>By default both are built and linked as shared libraries.</p>
<p>Building and linking boost as static library is only possibly by building it
from source. Specify the <tt class="docutils literal">BOOST_ROOT</tt> environment variable to point to the
root directory of the boost source distribution.</p>
<p>For example, to build a self-contained python module:</p>
<pre class="literal-block">
b2 release python=3.7 libtorrent-link=static boost-link=static
</pre>
</div>
<div class="section" id="helper-targets">
<h2>helper targets</h2>
<p>There are some targets for placing the build artifact in a helpful location:</p>
<pre class="literal-block">
$ b2 release python=3.7 stage_module stage_dependencies
</pre>
<p>This will produce a <tt class="docutils literal">libtorrent</tt> python module in the current directory (file
name extension depends on operating system). The libraries the python module depends
on will be copied into <tt class="docutils literal">./dependencies</tt>.</p>
<p>To install the python module, build it with the following command:</p>
<pre class="literal-block">
b2 release python=3.7 install_module
</pre>
<p>By default the module will be installed to the python user site. This can be
changed with the <tt class="docutils literal"><span class="pre">python-install-scope</span></tt> feature. The valid values are <tt class="docutils literal">user</tt>
(default) and <tt class="docutils literal">system</tt>. e.g.:</p>
<pre class="literal-block">
b2 release python=3.7 install_module python-install-scope=system
</pre>
<p>To specify a custom installation path for the python module, specify the desired
path with the <tt class="docutils literal"><span class="pre">python-install-path</span></tt> feature. e.g.:</p>
<pre class="literal-block">
b2 release python=3.7 install_module python-install-path=/home/foobar/python-site/
</pre>
</div>
</div>
<div class="section" id="using-libtorrent-in-python">
<h1>using libtorrent in python</h1>
<p>The python interface is nearly identical to the C++ interface. Please refer to
the <a class="reference external" href="reference.html">library reference</a>. The main differences are:</p>
<dl class="docutils">
<dt>asio::tcp::endpoint</dt>
<dd>The endpoint type is represented as a tuple of a string (as the address) and an int for
the port number. E.g. <tt class="docutils literal">(&quot;127.0.0.1&quot;, 6881)</tt> represents the localhost port 6881.</dd>
<dt>lt::time_duration</dt>
<dd>The time duration is represented as a number of seconds in a regular integer.</dd>
</dl>
<p>The following functions takes a reference to a container that is filled with
entries by the function. The python equivalent of these functions instead returns
a list of entries.</p>
<ul class="simple">
<li>torrent_handle::get_peer_info</li>
<li>torrent_handle::file_progress</li>
<li>torrent_handle::get_download_queue</li>
<li>torrent_handle::piece_availability</li>
</ul>
<p><tt class="docutils literal"><span class="pre">create_torrent::add_node()</span></tt> takes two arguments, one string and one integer,
instead of a pair. The string is the address and the integer is the port.</p>
<p><tt class="docutils literal"><span class="pre">session::apply_settings()</span></tt> accepts a dictionary with keys matching the names
of settings in settings_pack.
When calling <tt class="docutils literal">apply_settings</tt>, the dictionary does not need to have every settings set,
keys that are not present are not updated.</p>
<p>To get a python dictionary of the settings, call <tt class="docutils literal"><span class="pre">session::get_settings</span></tt>.</p>
<p>Retrieving session statistics in Python is more convenient than that in C++. The
statistics are stored as an array in <tt class="docutils literal">session_stats_alert</tt>, which will be
posted after calling <tt class="docutils literal">post_session_stats()</tt> in the <tt class="docutils literal">session</tt> object. In
order to interpret the statistics array, in C++ it is required to call
<tt class="docutils literal">session_stats_metrics()</tt> to get the indices of these metrics, while in Python
it can be done using <tt class="docutils literal"><span class="pre">session_stats_alert.values[&quot;NAME_OF_METRIC&quot;]</span></tt>, where
<tt class="docutils literal">NAME_OF_METRIC</tt> is the name of a metric.</p>
</div>
<div class="section" id="set-alert-notify">
<h1>set_alert_notify</h1>
<p>The <tt class="docutils literal">set_alert_notify()</tt> function is not compatible with python. Since it
requires locking the GIL from within the libtorrent thread, to call the callback,
it can cause a deadlock with the main thread.</p>
<p>Instead, use the python-specific <tt class="docutils literal">set_alert_fd()</tt> which takes a file descriptor
that will have 1 byte written to it to notify the client that there are new
alerts to be popped.</p>
<p>The file descriptor should be set to non-blocking mode. If writing to the
file/sending to the socket blocks, libtorrent's internal thread will stall.</p>
<p>This can be used with <tt class="docutils literal">socket.socketpair()</tt>, for example. The file descriptor
is what <tt class="docutils literal">fileno()</tt> returns on a socket.</p>
</div>
<div class="section" id="example">
<h1>Example</h1>
<p>For an example python program, see <tt class="docutils literal">client.py</tt> in the <tt class="docutils literal">bindings/python</tt>
directory.</p>
<p>A very simple example usage of the module would be something like this:</p>
<pre class="code python literal-block">
<span class="keyword namespace">import</span><span class="whitespace"> </span><span class="name namespace">libtorrent</span><span class="whitespace"> </span><span class="keyword">as</span><span class="whitespace"> </span><span class="name namespace">lt</span><span class="whitespace">
</span><span class="keyword namespace">import</span><span class="whitespace"> </span><span class="name namespace">time</span><span class="whitespace">
</span><span class="keyword namespace">import</span><span class="whitespace"> </span><span class="name namespace">sys</span><span class="whitespace">

</span><span class="name">ses</span> <span class="operator">=</span> <span class="name">lt</span><span class="operator">.</span><span class="name">session</span><span class="punctuation">({</span><span class="literal string single">'listen_interfaces'</span><span class="punctuation">:</span> <span class="literal string single">'0.0.0.0:6881'</span><span class="punctuation">})</span><span class="whitespace">

</span><span class="name">info</span> <span class="operator">=</span> <span class="name">lt</span><span class="operator">.</span><span class="name">torrent_info</span><span class="punctuation">(</span><span class="name">sys</span><span class="operator">.</span><span class="name">argv</span><span class="punctuation">[</span><span class="literal number integer">1</span><span class="punctuation">])</span><span class="whitespace">
</span><span class="name">h</span> <span class="operator">=</span> <span class="name">ses</span><span class="operator">.</span><span class="name">add_torrent</span><span class="punctuation">({</span><span class="literal string single">'ti'</span><span class="punctuation">:</span> <span class="name">info</span><span class="punctuation">,</span> <span class="literal string single">'save_path'</span><span class="punctuation">:</span> <span class="literal string single">'.'</span><span class="punctuation">})</span><span class="whitespace">
</span><span class="name">s</span> <span class="operator">=</span> <span class="name">h</span><span class="operator">.</span><span class="name">status</span><span class="punctuation">()</span><span class="whitespace">
</span><span class="name builtin">print</span><span class="punctuation">(</span><span class="literal string single">'starting'</span><span class="punctuation">,</span> <span class="name">s</span><span class="operator">.</span><span class="name">name</span><span class="punctuation">)</span><span class="whitespace">

</span><span class="keyword">while</span> <span class="punctuation">(</span><span class="operator word">not</span> <span class="name">s</span><span class="operator">.</span><span class="name">is_seeding</span><span class="punctuation">):</span><span class="whitespace">
</span>    <span class="name">s</span> <span class="operator">=</span> <span class="name">h</span><span class="operator">.</span><span class="name">status</span><span class="punctuation">()</span><span class="whitespace">

</span>    <span class="name builtin">print</span><span class="punctuation">(</span><span class="literal string single">'</span><span class="literal string escape">\r</span><span class="literal string interpol">%.2f%%</span><span class="literal string single"> complete (down: </span><span class="literal string interpol">%.1f</span><span class="literal string single"> kB/s up: </span><span class="literal string interpol">%.1f</span><span class="literal string single"> kB/s peers: </span><span class="literal string interpol">%d</span><span class="literal string single">) </span><span class="literal string interpol">%s</span><span class="literal string single">'</span> <span class="operator">%</span> <span class="punctuation">(</span><span class="whitespace">
</span>        <span class="name">s</span><span class="operator">.</span><span class="name">progress</span> <span class="operator">*</span> <span class="literal number integer">100</span><span class="punctuation">,</span> <span class="name">s</span><span class="operator">.</span><span class="name">download_rate</span> <span class="operator">/</span> <span class="literal number integer">1000</span><span class="punctuation">,</span> <span class="name">s</span><span class="operator">.</span><span class="name">upload_rate</span> <span class="operator">/</span> <span class="literal number integer">1000</span><span class="punctuation">,</span><span class="whitespace">
</span>        <span class="name">s</span><span class="operator">.</span><span class="name">num_peers</span><span class="punctuation">,</span> <span class="name">s</span><span class="operator">.</span><span class="name">state</span><span class="punctuation">),</span> <span class="name">end</span><span class="operator">=</span><span class="literal string single">' '</span><span class="punctuation">)</span><span class="whitespace">

</span>    <span class="name">alerts</span> <span class="operator">=</span> <span class="name">ses</span><span class="operator">.</span><span class="name">pop_alerts</span><span class="punctuation">()</span><span class="whitespace">
</span>    <span class="keyword">for</span> <span class="name">a</span> <span class="operator word">in</span> <span class="name">alerts</span><span class="punctuation">:</span><span class="whitespace">
</span>        <span class="keyword">if</span> <span class="name">a</span><span class="operator">.</span><span class="name">category</span><span class="punctuation">()</span> <span class="operator">&amp;</span> <span class="name">lt</span><span class="operator">.</span><span class="name">alert</span><span class="operator">.</span><span class="name">category_t</span><span class="operator">.</span><span class="name">error_notification</span><span class="punctuation">:</span><span class="whitespace">
</span>            <span class="name builtin">print</span><span class="punctuation">(</span><span class="name">a</span><span class="punctuation">)</span><span class="whitespace">

</span>    <span class="name">sys</span><span class="operator">.</span><span class="name">stdout</span><span class="operator">.</span><span class="name">flush</span><span class="punctuation">()</span><span class="whitespace">

</span>    <span class="name">time</span><span class="operator">.</span><span class="name">sleep</span><span class="punctuation">(</span><span class="literal number integer">1</span><span class="punctuation">)</span><span class="whitespace">

</span><span class="name builtin">print</span><span class="punctuation">(</span><span class="name">h</span><span class="operator">.</span><span class="name">status</span><span class="punctuation">()</span><span class="operator">.</span><span class="name">name</span><span class="punctuation">,</span> <span class="literal string single">'complete'</span><span class="punctuation">)</span>
</pre>
</div>

    </div>
    </div>
    <div id="gradient"></div>
    <div id="filler">
    <div id="footer">
    <div><a href="index.html">home</a></div>
    <div><a href="https://blog.libtorrent.org">blog</a></div>
    <div><a href="utp.html">uTP</a></div>
    <div><a href="https://sourceforge.net/projects/libtorrent/files/libtorrent/">download</a></div>
    <div><a href="reference.html">documentation</a></div>
    <div><a href="dht_store.html">DHT put extension</a></div>
    <div><a href="python_binding.html">python bindings</a></div>
    <div><a href="features-ref.html">features</a></div>
    <div><a href="dht_sec.html">DHT security extension</a></div>
    <div><a href="https://sourceforge.net/p/libtorrent/mailman/libtorrent-discuss/">mailing list archive</a></div>
    <div><a href="contributing.html">contributing</a></div>
    <div><a href="streaming.html">streaming</a></div>
    <div><a href="https://github.com/arvidn/libtorrent/issues">report a bug</a></div>
    <div><a href="building.html">building</a></div>
    <div><a href="bittorrent.pdf">bittorrent slides</a></div>
    </div>
	</div>

</div>
</body>
</html>
